package tcln.sors.client.core.mvc.modelmapping;

import tcln.sors.client.core.mvc.ModelData;

/**
 * Interface for a populator which populates changes from a {@link ModelData} to an arbitary object having the same
 * properties.
 * 
 * @author Truong Chau Lien Ngoc (lienngoc@gmail.com)
 */
public interface ModelDataPopulator {

    /**
     * Populates data from a given model data to a given destination object.
     * 
     * @param <E>
     * @param modelData
     *            Model data to populate.
     * @param destObject
     *            Destination object to be populated to; required.
     * @param full
     *            <code>true</code> to fully populate all properties; <code>false</code> to populate only dirty
     *            properties.
     * @return Populated object instance, usually the given object.
     */
    <E> E populate(ModelData<?> modelData, E destObject, boolean full);

    /**
     * Populates data from a given model data to a given destination object.
     * 
     * @param <E>
     * @param modelData
     *            Model data to populate.
     * @param destObjectClass
     *            Destination object class which is used to create object instance for population; required. This class
     *            must have a <i>default</i> constructor which is necessary to create model data instance. The
     *            visibility of this default constructor is, however, ignored.
     * @param full
     *            <code>true</code> to fully populate all properties; <code>false</code> to populate only dirty
     *            properties.
     * @return Populated object instance.
     */
    <E> E populate(ModelData<?> modelData, Class<E> destObjectClass, boolean full);
}
